# -*- coding:utf-8 -*-
# @FileName : app\api\v1\users\schemas.py
# @Time     : 2025/11/28
# @Author   : 天空之城
"""用户模块数据模式文件

此模块使用Marshmallow定义用户数据的验证和序列化模式。
"""
from marshmallow import Schema, fields, validate


class RoleSchema(Schema):
    """角色数据模式"""
    id = fields.Int(dump_only=True)
    name = fields.Str(required=True)
    description = fields.Str()

    class Meta:
        ordered = True


class UserSchema(Schema):
    """用户数据模式
    
    用于验证和序列化用户数据，定义了用户数据的结构和验证规则。
    """
    id = fields.Int(dump_only=True)  # 用户ID
    username = fields.Str(required=True, validate=validate.Length(min=3, max=50))  # 用户名
    email = fields.Email(required=True)  # 邮箱
    password = fields.Str(load_only=True, validate=validate.Length(min=6))  # 密码（仅加载时需要）
    created_at = fields.DateTime(dump_only=True)  # 创建时间
    updated_at = fields.DateTime(dump_only=True)  # 更新时间
    roles = fields.List(fields.Nested(RoleSchema), dump_only=True)  # 用户角色列表
    
    class Meta:
        """元数据
        
        指定JSON序列化的额外配置。
        """
        ordered = True


class RegisterCredentialsSchema(Schema):
    """用户注册数据模式
    
    用于验证用户注册请求的数据。
    """
    username = fields.Str(required=True, validate=validate.Length(min=3, max=50))  # 用户名
    password = fields.Str(required=True, validate=validate.Length(min=6))  # 密码
    confirm_password = fields.Str(required=True)  # 确认密码
    
    class Meta:
        ordered = True


class ForgotPasswordSchema(Schema):
    """忘记密码数据模式
    
    用于验证忘记密码请求的数据。
    """
    email = fields.Email(required=True)  # 邮箱
    
    class Meta:
        ordered = True
